<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>Chapter&nbsp;15.&nbsp;日志记录</title>
    <link rel="stylesheet" href="css/html.css" type="text/css">
    <meta name="generator" content="DocBook XSL Stylesheets V1.65.1">
    <link rel="home" href="index.html" title="JBoss jBPM 3.1">
    <link rel="up" href="index.html" title="JBoss jBPM 3.1">
    <link rel="previous" href="businesscalendar.html" title="Chapter&nbsp;14.&nbsp;Business calendar">
    <link rel="next" href="jpdl.html" title="Chapter&nbsp;16.&nbsp;jBPM Process Definition Language (JPDL)">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
    <table width="100%" summary="Navigation header">
        <tr>
            <th colspan="3" align="center">Chapter&nbsp;15.&nbsp;日志记录</th>
        </tr>
        <tr>
            <td width="20%" align="left"><a accesskey="p" href="businesscalendar.html">Prev</a>&nbsp;</td>
            <th width="60%" align="center">&nbsp;</th>
            <td width="20%" align="right">&nbsp;<a accesskey="n" href="jpdl.html">Next</a></td>
        </tr>
    </table>
    <hr>
</div>
<div class="chapter" lang="en">
    <div class="titlepage">
        <div>
            <div><h2 class="title"><a name="logging"></a>Chapter&nbsp;15.&nbsp;日志记录</h2></div>
        </div>
        <div></div>
    </div>
    <p>The purpose of logging is to keep track of the history of a
        process execution. As the runtime data of a process execution changes,
        all the delta's are stored in the logs.</p>

    <p>Process logging, which is covered in this chapter, is not to be confused
        with software logging. Software logging traces the execution of a software
        program (usually for debugging purposes). Process logging traces the execution
        of process instances.</p>

    <p>There are various use cases for process logging information. Most obvious is
        the consulting of the process history by participants of a process execution.
    </p>

    <p>Another use case is
        Business Activity Monitoring (BAM). BAM will query or analyse the logs of process
        executions to find usefull statistical information about the business process. E.g.
        how much time is spend on average in each step of the process ? Where are the
        bottlenecks in the process ? ... This information is key to implement real business
        process management in an organisation. Real business process management is about how
        an organisation manages their processes, how these are supported by information technology
        *and* how these two improve the other in an iterative process.
    </p>

    <p>Next use case is the undo functionality. Process logs can be used to implement
        the undo. Since the logs contain the delta's of the runtime information, the logs can be
        played in reverse order to bring the process back into a previous state.
    </p>

    <div class="section" lang="en">
        <div class="titlepage">
            <div>
                <div><h2 class="title" style="clear: both"><a name="creationoflogs"></a>15.1.&nbsp;日志的创建</h2>
                </div>
            </div>
            <div></div>
        </div>
        <p>Logs are produced by jBPM modules while they are running process executions.
            But also users can insert process logs. A log entry is a java object that inherits from
            <tt class="literal">org.jbpm.logging.log.ProcessLog</tt>. Process log entries are added to
            the <tt class="literal">LoggingInstance</tt>. The <tt class="literal">LoggingInstance</tt> is an
            optional extension of the <tt class="literal">ProcessInstance</tt>.
        </p>

        <p>Various kinds of logs are generated by jBPM : graph execution logs, context logs
            and task management logs. For more information about the specific data contained in
            those logs, we refer to the javadocs. A good starting point is the class
            <tt class="literal">org.jbpm.logging.log.ProcessLog</tt> since from that class you can navigate
            down the inheritance tree.</p>

        <p>The <tt class="literal">LoggingInstance</tt> will collect all the log entries. When
            the <tt class="literal">ProcessInstance</tt> is saved, all the logs in the <tt class="literal">LoggingInstance</tt>
            will be flushed to the database. The <tt class="literal">logs</tt>-field of a <tt class="literal">ProcessInstance</tt>
            is not mapped with hibernate to avoid that logs are retrieved from the database in each transactions.
            Each <tt class="literal">ProcessLog</tt> is made in the context
            of a path of execution (<tt class="literal">Token</tt>) and hence, the <tt class="literal">ProcessLog</tt>
            refers to that token. The <tt class="literal">Token</tt> also serves as an index-sequence generator
            for the index of the <tt class="literal">ProcessLog</tt> in the <tt class="literal">Token</tt>. This will
            be important for log retrieval. That way, logs that are produced in subsequent transactions
            will have sequential sequence numbers. (wow, that a lot of seq's in there :-s ).</p>

        <p>For deployments where logs are not important, it suffices to get rid of the optional
            <tt class="literal">LoggingDefinition</tt> in the <tt class="literal">ProcessDefinition</tt>. That will
            prevent <tt class="literal">LoggingInstance</tt>s from being captured and hence no logs will be
            maintained. We will add more fine grained configuration control over logging later on.
            See jira issue <a href="http://jira.jboss.com/jira/browse/JBPM-166" target="_top">'log level
            configuration'</a>.
        </p>

        <p>The API method for adding process logs is the following.
        </p><pre class="programlisting">public class LoggingInstance extends ModuleInstance {
  ...
  public void addLog(ProcessLog processLog) {...}
  ...
}</pre>
        <p>The UML diagram for logging information looks like this:</p>

        <div class="figure"><a name="logging.model.image"></a>

            <div class="mediaobject" align="center"><img src="images/logging.model.gif" align="middle"
                                                         alt="The jBPM logging information class diagram"></div>
            <p class="title"><b>Figure&nbsp;15.1.&nbsp;The jBPM logging information class diagram</b></p></div>
        <p>A <tt class="literal">CompositeLog</tt>
            is a special kind of log entry. It serves as a parent log for a number of child logs,
            thereby creating the means for a hierarchical structure in the logs.
            The API for inserting a log is the following.</p><pre class="programlisting">public class LoggingInstance extends ModuleInstance {
  ...
  public void startCompositeLog(CompositeLog compositeLog) {...}
  public void endCompositeLog() {...}
  ...
}</pre>
        <p>The <tt class="literal">CompositeLog</tt>s should always be called in a
            <tt class="literal">try-finally</tt>-block to make sure that the hierarchical
            structure of logs is consistent. For example:</p><pre class="programlisting">startCompositeLog(new MyCompositeLog());
try {
  ...
} finally {
  endCompositeLog();
}</pre>
    </div>
    <div class="section" lang="en">
        <div class="titlepage">
            <div>
                <div><h2 class="title" style="clear: both"><a name="logretrieval"></a>15.2.&nbsp;日志检索（Log retrieval）</h2>
                </div>
            </div>
            <div></div>
        </div>
        <p>As said before, logs cannot be retrieved from the database by navigating
            the LoggingInstance to its logs. Instead, logs of a process instance should always
            be queried from the database. The <tt class="literal">LoggingSession</tt> has 2 methods
            that serve this purpose.
        </p>

        <p>The first method retrieves all the logs for a process instance. These logs
            will be grouped by token in a Map. The map will associate a List of ProcessLogs
            with every Token in the process instance. The list will contain the ProcessLogs
            in the same ordered as they were created.</p><pre class="programlisting">public class LoggingSession {
  ...
  public Map findLogsByProcessInstance(long processInstanceId) {...}
  ...
}</pre>
        <p>The second method retrieves the logs for a specific Token. The returned list
            will contain the ProcessLogs in the same ordered as they were created.</p><pre class="programlisting">public class LoggingSession {
  public List findLogsByToken(long tokenId) {...}
  ...
}</pre>
    </div>
    <div class="section" lang="en">
        <div class="titlepage">
            <div>
                <div><h2 class="title" style="clear: both"><a name="datawarehousing"></a>15.3.&nbsp;数据仓库（Database warehousing）
                </h2></div>
            </div>
            <div></div>
        </div>
        <p>Sometimes you may want to apply data warehousing techniques to the jbpm
            process logs. Data warehousing means that you create a separate database containing
            the process logs to be used for various purposes.
        </p>

        <p>There may be many reasons why you want to create a data warehouse with the
            process log information. Sometimes it might be to offload heavy queryies from the
            'live' production database. In other situations it might be to do some extensive
            analysis. Data warehousing even might be done on a modified database schema which is
            optimized for its purpose.</p>

        <p>In this section, we only want to propose the technique of warehousing in
            the context of jBPM. The purposes are too diverse, preventing a generic solution
            to be included in jBPM that could cover all those requirements.</p></div>
</div>
<div class="navfooter">
    <hr>
    <table width="100%" summary="Navigation footer">
        <tr>
            <td width="40%" align="left"><a accesskey="p" href="businesscalendar.html">Prev</a>&nbsp;</td>
            <td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td>
            <td width="40%" align="right">&nbsp;<a accesskey="n" href="jpdl.html">Next</a></td>
        </tr>
        <tr>
            <td width="40%" align="left" valign="top">Chapter&nbsp;14.&nbsp;Business calendar&nbsp;</td>
            <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
            <td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;16.&nbsp;jBPM Process Definition Language
                (JPDL)
            </td>
        </tr>
    </table>
</div>
</body>
</html>